BOOL SetConsoleMode(HANDLE hConsoleHandle, DWORD fdevMode)
Возвращаемое значение: тогда, и только тогда, когда функция завершается успешно — TRUE, иначе — FALSE.
ПараметрыhConsoleHandle — дескриптор буфера ввода консоли или буфера дисплея, который должен быть создан с правами доступа GENERIC_WRITE, даже если устройство предназначено только для ввода информации.
Параметр fdevMode задает способ обработки символов. В имени каждого из его флагов содержится компонент, указывающий, к чему относится данный флаг— к вводу (input) или выводу (output). Ниже перечислены пять обычно используемых флагов, причем все они устанавливаются по умолчанию.
• ENABLE_LINE_INPUT — возврат из функции чтения (ReadConsole) происходит только после считывания символа возврата каретки.
• ENABLE_ECHO_INPUT — эхо-отображение вводимых символов на экране.
• ENABLE_PROCESSED_INPUT — установка этого флага приводит к обработке системой управляющих символов возврата на одну позицию, возврата каретки и перехода на новую строку.
• ENABLE_PROCESSED_OUTPUT — установка этого флага приводит к обработке системой управляющих символов возврата на одну позицию, табуляции, подачи звукового сигнала, возврата каретки и перехода на новую строку.
• ENABLE_WRAP_AT_EOL_OUTPUT — переход на следующую строку экрана как при обычном выводе символов, так и при их эхо-отображении в процессе ввода.
В случае неудачного завершения функции SetConsoleMode текущий режим остается неизменным, и функция возвращает значение FALSE. Как обычно, для получения номера ошибки следует воспользоваться функцией GetLastError.
Функции ReadConsole и WriteConsole аналогичны функциям ReadFile и WriteFile.
BOOL ReadConsole(HANDLE hConsoleInput, LPVOID lpBuffer, DWORD cchToRead, LPDWORD lpcchRead, LPVOID lpReserved)
Возвращаемое значение: тогда, и только тогда, когда функция завершается успешно — TRUE, иначе — FALSE.
Параметры у этой функции почти те же, что и у функции ReadFile. Значения обоих параметров, связанных с количеством подлежащих считыванию (cchToRead) и фактически считанных (lpcchRead) символов, выражаются в терминах обобщенных символов, а не байтов, а значение параметра lpReserved должно быть равным NULL. Как и во всех остальных подобных случаях, никогда не используйте для собственных нужд зарезервированные поля, аналогичные lpReserved, которые встречаются в некоторых функциях. Параметры функции WriteConsole имеют тот же смысл и не нуждаются в дополнительных пояснениях. В очередном примере будет проиллюстрировано применение функций Read-Console и WriteConsole, и, кроме того, будет показано, как использовать возможности управления режимом консоли.
Любому процессу в каждый момент времени может быть назначена только одна консоль. Приложениям того типа, с которым мы имели дело до сих пор, консоль передается обычно на стадии инициализации. Однако в целом ряде других случаев, например, в случае серверных или GUI-приложений, у вас может возникнуть необходимость в получении отдельной консоли, на которую можно было бы выводить информацию о состоянии программы или отладочную информацию. Для этих целей можно воспользоваться двумя простыми функциями, не имеющими параметров.
BOOL FreeConsole(VOID)
BOOL AllocConsole(VOID)
Функция FreeConsole отключает процесс от его консоли, тогда как функция AllocConsole создает новую консоль, ассоциированную с дескрипторами стандартного ввода информации, стандартного вывода информации и стандартного вывода сообщений об ошибках, принадлежащими данному процессу. Если консоль у процесса уже имеется, функция AllocConsole завершится с ошибкой; чтобы избежать этого, следует предварительно вызывать функцию FreeConsole.
Примечание
GUI-приложения Windows не имеют консоли по умолчанию и должны получить ее, прежде чем смогут воспользоваться функциями WriteConsole или printf для вывода на консоль. Процессы на стороне сервера также могут не иметь консоли. О том, как создать процесс без консоли, рассказано в главе 6.
Имеется также множество других функций консольного ввода/вывода, предназначенных для установки позиции курсора, а также задания атрибутов выводимых символов (например, цвета) и так далее. Принятый в данной книге подход состоит в том, чтобы использовать лишь те функции, которые необходимы для создания примеров работоспособных программ, поэтому углубляться больше, чем это необходимо, в пользовательские интерфейсы мы не будем. После того как вы разберете примеры, для вас не составит большого труда изучить дополнительные функции, воспользовавшись справочными материалами.
Исторически сложилось так, что ОС Windows ориентирована на использование терминалов или консолей в меньшей степени, чем UNIX, и не полностью воспроизводит функциональные средства UNIX, поддерживающие работу с терминалами. В книге [40] одна из глав посвящена рассмотрению обеспечиваемых UNIX возможностей терминального ввода/вывода (глава 11), а другая — псевдотерминалам (глава 19).
Разумеется, работа в Windows почти всегда ведется с использованием мощных графических интерфейсов, поддерживающих мышь и ввод с клавиатуры. Несмотря на то что рассмотрение GUI выходит за рамки данной книги, все, что мы здесь обсуждаем, будет работать и в GUI-приложениях.
Пример: вывод на консоль сообщений и подсказок для пользователя
Функция ConsolePrompt, входящая в программу 2.1, является полезной утилитой, которая выводит на консоль заданное сообщение и возвращает ответ пользователя на него. Данная утилита предусматривает возможность подавления эхо-отображения ответной информации, полученной от пользователя. В указанной функции используются функции консольного ввода/вывода и обобщенные символы. Двумя другими точками входа в этом модуле являются функции Print-Strings и PrintMsg; эти функции допускают использование любого дескриптора, однако обычно они применяются совместно с дескрипторами устройств стандартного вывода информации и стандартного вывода сообщений об ошибках. В первой функции разрешается использовать список аргументов переменной длины, тогда как во второй в качестве аргумента можно задавать только одну строку, что в некоторых случаях может оказаться удобнее. Для обработки списка аргументов переменной длины функция PrintStrings использует функции va_start, va_arg и va_end стандартной библиотеки С.
Описанные функции, а также функции из обобщенной библиотеки С будут привлекаться для использования в приводимых в данной книге примерах программ при всякой удобной возможности.
Примечание
Коды программ, находящиеся на Web-сайте книги, содержат подробные комментарии и тщательно документированы, тогда как в самой книге большинство комментариев с целью сокращения места были опущены, и основное внимание в ней уделяется использованию Windows.
Следует также отметить, что в примере вводится заголовочный файл Envirmnt.h (его код приведен в приложении А и предоставлен на Web-сайте книги), который должен использоваться совместно со всеми приводимыми в книге программами. Этот файл содержит определения символических констант UNICODE и _UNICODE (сами определения "закомментированы"; при компоновке приложений, предназначенных для работы с символами стандарта Unicode, символы комментариев следует удалить), а также необходимых макропеременных, учитывающих особенности окружения. В заголовочных файлах, находящихся на Web-сайте, определены также дополнительные модификаторы, которые обеспечивают импортирование и экспортирование имен функций, а также гарантируют соблюдение соответствующих соглашений о вызове функций.
Программа 2.1. PrintMsg: вспомогательные функции вывода на консоль сообщений и ожидания ответа от пользователя
/* PrintMsg.с: ConsolePrompt, PrintStrings, PrintMsg */
#include "Envirmnt.h" /* В этом файле устанавливаются директивы #define и #undef для UNICODE. */
#include <windows.h>
#include <stdarg.h>
BOOL PrintStrings (HANDLE hOut, ...)
/* Запись сообщений в буфер экрана консоли. */
{
DWORD MsgLen, Count;
LPCTSTR pMsg;
va_list pMsgList; /* Строка текущего сообщения. */
va_start (pMsgList, hOut); /* Начать обработку сообщений. */
while ((pMsg = va_arg(pMsgList, LPCTSTR)) != NULL) {
MsgLen = _tcslen(pMsg);
/* Функция WriteConsole может применяться только с дескриптором буфера экрана консоли. */
if (!WriteConsole(hOut, pMsg, MsgLen, &Count, NULL)
/* Функция WriteFile вызывается только в случае неудачного завершения функции WriteConsole. */
&& !WriteFile(hOut, pMsg, MsgLen * sizeof (TCHAR), &Count, NULL)) return FALSE;
}
va_end(pMsgList);
return TRUE;
}
BOOL PrintMsg(HANDLE hOut, LPCTSTR pMsg)
/* Версия PrintStrings для вывода одиночного сообщения. */
{
return PrintStrings(hOut, pMsg, NULL);
}
BOOL ConsolePrompt(LPCTSTR pPromptMsg, LPTSTR pResponse, DWORD MaxTchar, BOOL Echo)
