Параметры. HConsoleHandle — дескриптор буфера ввода консоли или буфера дисплея, который должен быть создан с правами доступа GENERIC_WRITE
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)
/* Вывести на консоль подсказку для пользователя и получить от него ответ. */
{
HANDLE hStdIn, hStdOut;
DWORD TcharIn, EchoFlag;
BOOL Success;
hStdIn = CreateFile(_T("CONIN$"), GENERIC_READ | GENERIC_WRITE, 0, NULL, OPEN_ALWAYS, FILE_ATTRIBUTE_NORMAL, NULL);
hStdOut = CreateFile(_T("CONOUT$"), GENERIC_WRITE, 0, NULL, OPEN_ALWAYS, FILE_ATTRIBUTE_NORMAL, NULL);
EchoFlag = Echo ? ENABLE_ECHO_INPUT : 0;
Success = SetConsoleMode(hStdIn, ENABLE_LINE_INPUT | EchoFlag | ENABLE_PROCESSED_INPUT) &&
SetConsoleMode (hStdOut, ENABLE_WRAP_AT_EOL_OUTPUT | ENABLE_PROCESSED_OUTPUT) &&
PrintStrings (hStdOut, pPromptMsg, NULL) &&
ReadConsole (hStdIn, pResponse, MaxTchar, &TcharIn, NULL);
if (Success) pResponse [TcharIn – 2] = '\0';
CloseHandle (hStdIn);
CloseHandle (hStdOut);
return Success;
}
Обратите внимание, что при вычислении возвращаемого функцией значения булевской переменной Success, которое служит индикатором успешности выполнения, в программе, с выгодой для логики ее работы, используется тот факт, что стандартом ANSI С гарантируется так называемое "сокращенное" вычисление логических выражений в направлении слева направо; поэтому, как только при вычислении части выражения, расположенной слева от любой из операций логического "и" (&&), в качестве результата будет получено значение FALSE, остальная часть выражения, расположенная справа от данной операции, вычисляться не будет, поскольку результат вычисления всего выражения в целом оказывается предопределенным. Данный стиль написания программ может показаться чересчур компактным, однако он обладает тем преимуществом, что позволяет организовать логически стройную и понятную последовательность системных вызовов, не загромождая программу многочисленными операторами условных переходов. Для получения более подробной информации о возможных ошибках можно воспользоваться функцией GetLastError. Распространенный в Windows возврат функциями логических значений поощряет подобную практику.
В данной функции сообщения об ошибках не выводятся; их вывод, если это будет необходимо, можно предусмотреть в вызывающей программе.
В программном коде используется тот документированный факт, что при использовании функции WriteConsole вместе с дескриптором, который не является дескриптором консоли, ее выполнение будет завершено с ошибкой. В связи с этим предварительный запрос свойств дескриптора не является обязательным. Функция воспользуется консольным режимом лишь в том случае, если указанный в ее вызове дескриптор действительно связан с консолью.
Кроме того, функция ReadConsole возвращает управляющие символы возврата каретки и перехода на новую строку, что диктует необходимость вставки дополнительных нулевых символов после символов возврата каретки в соответствующих местах.
Пример: обработка ошибок
В программе 1.2 было продемонстрировано использование лишь самых примитивных средств обработки ошибок, а именно, получение номера ошибки в переменной типа DWORD с помощью функции GetLastError. Вызов функции, а не просто получение глобального номера ошибки, как это делается при помощи функции UNIX errno, гарантирует уникальную идентификацию системных ошибок для каждого из потоков (глава 7), использующих разделяемую область хранения данных.
Функция FormatMessage превращает простой номер сообщения в описательное сообщение, представляющее собой фразу на английском или любом другом из множества возможных языков, и возвращает размер сообщения.
В программе 2.2 представлена полезная универсальная функция ReportError, предназначенная для обработки ошибок и по своим возможностям аналогичная входящей в состав библиотеки С функции perror, а также описанным в [40] функциям err_sys и err_ret. Функция ReportError передает в выходной буфер сообщение в виде, определяемом первым аргументом, и либо прекращает выполнение с кодом выхода по ошибке, либо осуществляет обычный возврат управления, в зависимости от значения второго аргумента. Третий аргумент определяет, должны ли отображаться системные сообщения об ошибках.
Обратите внимание на аргументы функции FormatMessage. В качестве одного из параметров используется значение, возвращаемое функцией GetLastError, a на необходимость генерации сообщения системой указывает флаг. Сгенерированное сообщение сохраняется в буфере, выделяемом функцией, а соответствующий адрес возвращается в параметре. Имеются также другие параметры, для которых указаны значения по умолчанию. Язык сообщений может быть задан как во время компиляции, так и во время выполнения. В этой книге функция Format-Message далее нигде не используется, поэтому никаких дополнительных пояснений относительно нее в тексте не дается.
Функция ReportError упрощает обработку ошибок, и будет использоваться почти во всех последующих примерах. В главе 4 она будет модифицирована для генерации исключений.
В программе 2.2 вводится заголовочный файл EvryThng.h. Как следует из самого его названия, этот файл включает в себя файлы <windows.h>, Envirmnt.h и все остальные заголовочные файлы, которые были явно указаны в программе 2.1. Кроме того, в нем описаны такие обычно используемые функции, как PrintMsg, PrintStrings и ReportError. Во всех остальных примерах будет использоваться только этот заголовочный файл, листинг которого приведен в приложении А.
Обратите внимание на вызов функции HeapFree, находящийся почти в конце программы. Об этой функции будет рассказано в главе 5.