[CONUTILS] Fix and improve the documentation for "outstream" and "utils", addendum...
[reactos.git] / sdk / lib / conutils / utils.c
1 /*
2 * PROJECT: ReactOS Console Utilities Library
3 * LICENSE: GPL-2.0+ (https://spdx.org/licenses/GPL-2.0+)
4 * PURPOSE: Base set of functions for loading string resources
5 * and message strings, and handle type identification.
6 * COPYRIGHT: Copyright 2017-2018 ReactOS Team
7 * Copyright 2017-2018 Hermes Belusca-Maito
8 */
9
10 /**
11 * @file utils.c
12 * @ingroup ConUtils
13 *
14 * @brief General-purpose utility functions (wrappers around
15 * or reimplementations of Win32 APIs).
16 **/
17
18 /* FIXME: Temporary HACK before we cleanly support UNICODE functions */
19 #define UNICODE
20 #define _UNICODE
21
22 #include <windef.h>
23 #include <winbase.h>
24 #include <winnls.h>
25 #include <winuser.h> // MAKEINTRESOURCEW, RT_STRING
26 #include <wincon.h> // Console APIs (only if kernel32 support included)
27 #include <strsafe.h>
28
29 /* PSEH for SEH Support */
30 #include <pseh/pseh2.h>
31
32 // #include "conutils.h"
33 #include "utils.h"
34
35 #if 0 // The following function may be useful in the future...
36
37 // Performs MultiByteToWideChar then WideCharToMultiByte .
38 // See https://github.com/pcman-bbs/pcman-windows/blob/master/Lite/StrUtils.h#l33
39 // and http://www.openfoundry.org/svn/pcman/branches/OpenPCMan_2009/Lite/StrUtils.cpp
40 // for the idea.
41 int
42 MultiByteToMultiByte(
43 // IN WORD wTranslations,
44 IN DWORD dwFlags,
45 IN UINT SrcCodePage,
46 IN LPCSTR lpSrcString,
47 IN int cbSrcChar,
48 IN UINT DestCodePage,
49 OUT LPSTR wDestString OPTIONAL,
50 IN int cbDestChar
51 );
52
53 #endif
54
55 /**
56 * @name K32LoadStringExW
57 * Loads a string resource from the executable file associated with a
58 * specified module, copies the string into a buffer, and appends a
59 * terminating null character.
60 * This is basically the LoadString() API ripped from user32.dll to
61 * remove any dependency of ConUtils from user32.dll, and to add support
62 * for loading strings from other languages than the current one.
63 *
64 * @param[in] hInstance
65 * Optional handle to an instance of the module whose executable file
66 * contains the string resource. Can be set to NULL to get the handle
67 * to the application itself.
68 *
69 * @param[in] uID
70 * The identifier of the string to be loaded.
71 *
72 * @param[in] LanguageId
73 * The language identifier of the resource. If this parameter is
74 * <tt>MAKELANGID(LANG_NEUTRAL, SUBLANG_NEUTRAL)</tt>, the current language
75 * associated with the calling thread is used. To specify a language other
76 * than the current language, use the @c MAKELANGID macro to create this
77 * parameter.
78 *
79 * @param[out] lpBuffer
80 * The buffer that receives the string. Must be of sufficient length
81 * to hold a pointer (8 bytes).
82 *
83 * @param[in] nBufferMax
84 * The size of the buffer, in characters. The string is truncated and
85 * NULL-terminated if it is longer than the number of characters specified.
86 * If this parameter is 0, then @p lpBuffer receives a read-only pointer
87 * to the resource itself.
88 *
89 * @return
90 * If the function succeeds, the return value is the number of characters
91 * copied into the buffer, not including the terminating null character,
92 * or zero if the string resource does not exist. To get extended error
93 * information, call GetLastError().
94 *
95 * @see LoadString(), K32LoadStringW()
96 **/
97 INT
98 WINAPI
99 K32LoadStringExW(
100 IN HINSTANCE hInstance OPTIONAL,
101 IN UINT uID,
102 IN LANGID LanguageId,
103 OUT LPWSTR lpBuffer,
104 IN INT nBufferMax)
105 {
106 HRSRC hrsrc;
107 HGLOBAL hmem;
108 WCHAR *p;
109 UINT i;
110
111 if (!lpBuffer)
112 return 0;
113
114 /* Use LOWORD (incremented by 1) as ResourceID */
115 /* There are always blocks of 16 strings */
116 hrsrc = FindResourceExW(hInstance,
117 (LPCWSTR)RT_STRING,
118 MAKEINTRESOURCEW((LOWORD(uID) >> 4) + 1),
119 LanguageId);
120 if (!hrsrc) return 0;
121
122 hmem = LoadResource(hInstance, hrsrc);
123 if (!hmem) return 0;
124
125 p = LockResource(hmem);
126 // FreeResource(hmem);
127
128 /* Find the string we're looking for */
129 uID &= 0x000F; /* Position in the block, same as % 16 */
130 for (i = 0; i < uID; i++)
131 p += *p + 1;
132
133 /*
134 * If nBufferMax == 0, then return a read-only pointer
135 * to the resource itself in lpBuffer it is assumed that
136 * lpBuffer is actually a (LPWSTR *).
137 */
138 if (nBufferMax == 0)
139 {
140 *((LPWSTR*)lpBuffer) = p + 1;
141 return *p;
142 }
143
144 i = min(nBufferMax - 1, *p);
145 if (i > 0)
146 {
147 memcpy(lpBuffer, p + 1, i * sizeof(WCHAR));
148 lpBuffer[i] = L'\0';
149 }
150 else
151 {
152 if (nBufferMax > 1)
153 {
154 lpBuffer[0] = L'\0';
155 return 0;
156 }
157 }
158
159 return i;
160 }
161
162 /**
163 * @name K32LoadStringW
164 * Loads a string resource from the executable file associated with a
165 * specified module, copies the string into a buffer, and appends a
166 * terminating null character.
167 * This is a restricted version of K32LoadStringExW().
168 *
169 * @see LoadString(), K32LoadStringExW()
170 **/
171 INT
172 WINAPI
173 K32LoadStringW(
174 IN HINSTANCE hInstance OPTIONAL,
175 IN UINT uID,
176 OUT LPWSTR lpBuffer,
177 IN INT nBufferMax)
178 {
179 // NOTE: Instead of using LANG_NEUTRAL, one might use LANG_USER_DEFAULT...
180 return K32LoadStringExW(hInstance, uID,
181 MAKELANGID(LANG_NEUTRAL, SUBLANG_NEUTRAL),
182 lpBuffer, nBufferMax);
183 }
184
185 /**
186 * @name FormatMessageSafeW
187 * Loads and formats a message string. The function requires a message
188 * definition as input. The message definition can come from a buffer
189 * passed to the function. It can come from a message table resource in
190 * an already-loaded module, or the caller can ask the function to search
191 * the system's message table resource(s) for the message definition.
192 * Please refer to the Win32 FormatMessage() function for more details.
193 *
194 * @param[in] dwFlags
195 * The formatting options, and how to interpret the @p lpSource parameter.
196 * See FormatMessage() for more details.
197 *
198 * @param[in] lpSource
199 * The location of the message definition. The type of this parameter
200 * depends upon the settings in the @p dwFlags parameter.
201 *
202 * @param[in] dwMessageId
203 * The message identifier for the requested message. This parameter
204 * is ignored if @p dwFlags includes @b FORMAT_MESSAGE_FROM_STRING.
205 *
206 * @param[in] dwLanguageId
207 * The language identifier for the requested message. This parameter
208 * is ignored if @p dwFlags includes @b FORMAT_MESSAGE_FROM_STRING.
209 *
210 * @param[out] lpBuffer
211 * A pointer to a buffer that receives the null-terminated string that
212 * specifies the formatted message. If @p dwFlags includes
213 * @b FORMAT_MESSAGE_ALLOCATE_BUFFER, the function allocates a buffer
214 * using the LocalAlloc() function, and places the pointer to the buffer
215 * at the address specified in @p lpBuffer.
216 * This buffer cannot be larger than 64kB.
217 *
218 * @param[in] nSize
219 * If the @b FORMAT_MESSAGE_ALLOCATE_BUFFER flag is not set, this parameter
220 * specifies the size of the output buffer, in @b TCHARs.
221 * If @b FORMAT_MESSAGE_ALLOCATE_BUFFER is set, this parameter specifies
222 * the minimum number of @b TCHARs to allocate for an output buffer.
223 * The output buffer cannot be larger than 64kB.
224 *
225 * @param[in] Arguments
226 * Optional pointer to an array of values describing a variable number of
227 * arguments, depending on the message string. Each argument is used to
228 * replace an <em>insert sequence</em> in the message string.
229 * By default, the @p Arguments parameter is of type @c va_list*, initialized
230 * with va_start(). The state of the @c va_list argument is undefined upon
231 * return from the function. To use the @c va_list again, destroy the variable
232 * argument list pointer using va_end() and reinitialize it with va_start().
233 * If you do not have a pointer of type @c va_list*, then specify the
234 * @b FORMAT_MESSAGE_ARGUMENT_ARRAY flag and pass a pointer to an array
235 * of @c DWORD_PTR values; those values are input to the message formatted
236 * as the insert values. Each insert must have a corresponding element in
237 * the array.
238 *
239 * @return
240 * If the function succeeds, the return value is the number of characters
241 * copied into the buffer, not including the terminating null character,
242 * or zero if the string resource does not exist. To get extended error
243 * information, call GetLastError().
244 *
245 * @remark
246 * This function is a "safe" version of FormatMessage(), that does not
247 * crash if a malformed source string is retrieved and then being used
248 * for formatting. It basically wraps calls to FormatMessage() within SEH.
249 *
250 * @see <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms679351(v=vs.85).aspx">FormatMessage() (on MSDN)</a>
251 **/
252 DWORD
253 WINAPI
254 FormatMessageSafeW(
255 IN DWORD dwFlags,
256 IN LPCVOID lpSource OPTIONAL,
257 IN DWORD dwMessageId,
258 IN DWORD dwLanguageId,
259 OUT LPWSTR lpBuffer,
260 IN DWORD nSize,
261 IN va_list *Arguments OPTIONAL)
262 {
263 DWORD dwLength = 0;
264
265 _SEH2_TRY
266 {
267 /*
268 * Retrieve the message string. Wrap in SEH
269 * to protect from invalid string parameters.
270 */
271 _SEH2_TRY
272 {
273 dwLength = FormatMessageW(dwFlags,
274 lpSource,
275 dwMessageId,
276 dwLanguageId,
277 lpBuffer,
278 nSize,
279 Arguments);
280 }
281 _SEH2_EXCEPT(EXCEPTION_EXECUTE_HANDLER)
282 {
283 dwLength = 0;
284
285 /*
286 * An exception occurred while calling FormatMessage, this is usually
287 * the sign that a parameter was invalid, either 'lpBuffer' was NULL
288 * but we did not pass the flag FORMAT_MESSAGE_ALLOCATE_BUFFER, or the
289 * array pointer 'Arguments' was NULL or did not contain enough elements,
290 * and we did not pass the flag FORMAT_MESSAGE_IGNORE_INSERTS, and the
291 * message string expected too many inserts.
292 * In this last case only, we can call again FormatMessage but ignore
293 * explicitely the inserts. The string that we will return to the user
294 * will not be pre-formatted.
295 */
296 if (((dwFlags & FORMAT_MESSAGE_ALLOCATE_BUFFER) || lpBuffer) &&
297 !(dwFlags & FORMAT_MESSAGE_IGNORE_INSERTS))
298 {
299 /* Remove any possible harmful flags and always ignore inserts */
300 dwFlags &= ~FORMAT_MESSAGE_ARGUMENT_ARRAY;
301 dwFlags |= FORMAT_MESSAGE_IGNORE_INSERTS;
302
303 /* If this call also throws an exception, we are really dead */
304 dwLength = FormatMessageW(dwFlags,
305 lpSource,
306 dwMessageId,
307 dwLanguageId,
308 lpBuffer,
309 nSize,
310 NULL /* Arguments */);
311 }
312 }
313 _SEH2_END;
314 }
315 _SEH2_FINALLY
316 {
317 }
318 _SEH2_END;
319
320 return dwLength;
321 }
322
323 /**
324 * @name IsTTYHandle
325 * Checks whether a handle refers to a valid TTY object.
326 * A TTY object may be a console or a "communications" (e.g. serial) port.
327 *
328 * @param[in] hHandle
329 * Handle to the TTY object to check for.
330 *
331 * @return
332 * @b TRUE when the handle refers to a valid TTY object,
333 * @b FALSE if it does not.
334 *
335 * @remark
336 * This test is more general than IsConsoleHandle() as it is not limited
337 * to Win32 console objects only.
338 *
339 * @see IsConsoleHandle()
340 **/
341 BOOL
342 IsTTYHandle(IN HANDLE hHandle)
343 {
344 /*
345 * More general test than IsConsoleHandle(). Consoles, as well as serial
346 * (communications) ports, etc... verify this test, but only consoles
347 * verify the IsConsoleHandle() test: indeed the latter checks whether
348 * the handle is really handled by the console subsystem.
349 */
350 return ((GetFileType(hHandle) & ~FILE_TYPE_REMOTE) == FILE_TYPE_CHAR);
351 }
352
353 /**
354 * @name IsConsoleHandle
355 * Checks whether a handle refers to a valid Win32 console object.
356 *
357 * @param[in] hHandle
358 * Handle to the Win32 console object to check for:
359 * console input buffer, console output buffer.
360 *
361 * @return
362 * @b TRUE when the handle refers to a valid Win32 console object,
363 * @b FALSE if it does not.
364 *
365 * @see IsTTYHandle()
366 **/
367 BOOL
368 IsConsoleHandle(IN HANDLE hHandle)
369 {
370 DWORD dwMode;
371
372 /* Check whether the handle may be that of a console... */
373 if ((GetFileType(hHandle) & ~FILE_TYPE_REMOTE) != FILE_TYPE_CHAR)
374 return FALSE;
375
376 /*
377 * It may be. Perform another test. The idea comes from the
378 * MSDN description of the WriteConsole API:
379 *
380 * "WriteConsole fails if it is used with a standard handle
381 * that is redirected to a file. If an application processes
382 * multilingual output that can be redirected, determine whether
383 * the output handle is a console handle (one method is to call
384 * the GetConsoleMode function and check whether it succeeds).
385 * If the handle is a console handle, call WriteConsole. If the
386 * handle is not a console handle, the output is redirected and
387 * you should call WriteFile to perform the I/O."
388 */
389 return GetConsoleMode(hHandle, &dwMode);
390 }
391
392 /* EOF */