Windows System Programming Third Edition [Electronic resources] نسخه متنی

Standard Devices and Console I/O

Like UNIX, Windows has three standard devices for input, output, and error reporting. UNIX uses well-known values for the file descriptors (0, 1, and 2), but Windows requires handles and provides a function to obtain them for the standard devices.

HANDLE GetStdHandle (DWORD nStdHandle)

Return: A valid handle if the function succeeds; INVALID_HANDLE_VALUE otherwise.

Parameters

nStdHandle must have one of these values:

• STD_INPUT_HANDLE

• STD_OUTPUT_HANDLE

• STD_ERROR_HANDLE

The standard device assignments are normally the console and the keyboard. Standard I/O can be redirected.

GetStdHandle does not create a new or duplicate handle on a standard device. Successive calls with the same device argument return the same handle value. Closing a standard device handle makes the device unavailable for future use. For this reason, the examples often obtain a standard device handle but do not close it.

BOOL SetStdHandle (
DWORD nStdHandle,
HANDLE hHandle)

Return: trUE or FALSE indicating success or failure.

Parameters

In SetStdHandle, nStdHandle has the same possible values as in GetStdHandle. hHandle specifies an open file that is to be the standard device.

One method for redirecting standard I/O within a process is to use SetStdHandle followed by GetStdHandle. The resulting handle is used in subsequent I/O operations.

There are two reserved pathnames for console input (the keyboard) and console output: "CONIN$" and "CONOUT$". Initially, standard input, output, and error are assigned to the console. It is possible to use the console regardless of any redirection to these standard devices; just open handles to "CONIN$" or "CONOUT$" using CreateFile.

Console I/O can be performed with ReadFile and WriteFile, but it is simpler to use the specific console I/O functions, ReadConsole and WriteConsole. The principal advantages are that these functions process generic characters (TCHAR) rather than bytes, and they also process characters according to the console mode, which is set with the SetConsoleMode function.

BOOL SetConsoleMode (
HANDLE hConsoleHandle,
DWORD fdevMode)

Return: TRUE if and only if the function succeeds.

Parameters

hConsoleHandle identifies a console input or screen buffer, which must have GENERIC_WRITE access even if it is an input-only device.

fdevMode specifies how characters are processed. Each flag name indicates whether the flag applies to console input or output. Five commonly used flags are listed here; they are all enabled by default.

• ENABLE_LINE_INPUT
  A read function (ReadConsole) returns when a carriage return character is encountered.

• ENABLE_ECHO_INPUT
  Characters are echoed to the screen as they are read.

• ENABLE_PROCESSED_INPUT
  This flag causes the system to process backspace, carriage return, and line feed characters.

• ENABLE_PROCESSED_OUTPUT
  This flag causes the system to process backspace, tab, bell, carriage return, and line feed characters.

• ENABLE_WRAP_AT_EOL_OUTPUT
  Line wrap is enabled for both normal and echoed output.

If SetConsoleMode fails, the mode is unchanged and the function returns FALSE. GetLastError will, as is always the case, return the error code number.

The ReadConsole and WriteConsole functions are similar to ReadFile and WriteFile.

BOOL ReadConsole (HANDLE hConsoleInput,
LPVOID lpBuffer,
DWORD cchToRead,
LPDWORD lpcchRead,
LPVOID lpReserved)

Return: trUE if and only if the read succeeds.

The parameters are nearly the same as with ReadFile. The two length parameters are in terms of generic characters rather than bytes, and lpReserved must be NULL. Never use any of the reserved fields that occur in some functions. WriteConsole is now self-explanatory. The next example shows how to use ReadConsole and WriteConsole with generic strings and how to take advantage of the console mode.

A process can have only one console at a time. Applications such as the ones developed so far are normally initialized with a console. In many cases, such as a server or GUI application, however, you may need a console to display status or debugging information. There are two simple parameterless functions for this purpose.

BOOL FreeConsole (VOID)
BOOL AllocConsole (VOID)

FreeConsole detaches a process from its console. Calling AllocConsole then creates a new one associated with the process's standard input, output, and error handles. AllocConsole will fail if the process already has a console; to avoid this problem, precede the call with FreeConsole.

Note:
Windows GUI applications do not have a default console and must allocate one before using functions such as WriteConsole or printf to display on a console. It's also possible that server processes may not have a console. Chapter 6 shows how a process can be created without a console.

There are numerous other console I/O functions for specifying cursor position, screen attributes (such as color), and so on. This book's approach is to use only those functions needed to get the examples to work and not to wander further than necessary into user interfaces. Additional functions will be easy for you to learn from the reference material after you see the examples.