Функция ReadConsole

Статья
07/12/2023

Считывает входные данные символов из буфера ввода консоли и удаляет его из буфера.

Синтаксис

BOOL WINAPI ReadConsole(
  _In_     HANDLE  hConsoleInput,
  _Out_    LPVOID  lpBuffer,
  _In_     DWORD   nNumberOfCharsToRead,
  _Out_    LPDWORD lpNumberOfCharsRead,
  _In_opt_ LPVOID  pInputControl
);

Параметры

hConsoleInput [in]
Дескриптор входного буфера консоли. Этот дескриптор должен иметь право доступа GENERIC_READ. Дополнительные сведения см. в статье Безопасность и права доступа для буфера консоли.

lpBuffer [out]
Указатель на буфер, получающий данные из входного буфера консоли.

nNumberOfCharsToRead [in]
Число символов для чтения. Размер буфера, на который указывает параметр lpBuffer , должен быть не менее nNumberOfCharsToRead * sizeof(TCHAR) байтов.

lpNumberOfCharsRead [out]
Указатель на переменную, получающую количество символов, фактически считываемых.

pInputControl [in, необязательный]
Указатель на структуру CONSOLE_READCONSOLE_CONTROL , указывающую символ элемента управления для сигнала о завершении операции чтения. Этот параметр может принимать значение NULL.

Этот параметр требует ввода Юникода по умолчанию. Для режима ANSI задайте для этого параметра значение NULL.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Замечания

ReadConsole считывает входные данные клавиатуры из входного буфера консоли. Она ведет себя как функция ReadFile , за исключением того, что она может читаться в режиме Юникода (широкий символ) или ANSI. Чтобы иметь приложения, поддерживающие один набор источников, совместимых с обоими режимами, используйте ReadConsole , а не ReadFile. Хотя ReadConsole можно использовать только с дескриптором входного буфера консоли, ReadFile можно использовать с другими дескрипторами (например, с файлами или каналами). ReadConsole завершается ошибкой, если используется со стандартным дескриптором, который был перенаправлен для того, чтобы быть чем-то, кроме дескриптора консоли.

Все режимы ввода, влияющие на поведение ReadFile, имеют одинаковый эффект на ReadConsole. Чтобы получить и задать входные режимы буфера ввода консоли, используйте функции GetConsoleMode и SetConsoleMode.

Если входной буфер содержит события ввода, отличные от событий клавиатуры (например, события мыши или события изменения размера окна), они не карта. Эти события можно считывать только с помощью функции ReadConsoleInput.

Эта функция использует либо символы Юникода, либо 8-разрядные символы из текущей кодовой страницы консоли. Кодовая страница консоли по умолчанию изначально соответствует кодовой странице OEM системы. Чтобы изменить кодовую страницу консоли, используйте функции SetConsoleCP или SetConsoleOutputCP. Пользователи прежних версий могут также использовать команды chcp или mode con cp select= (но это не рекомендуется для новой разработки).

Параметр pInputControl можно использовать для включения промежуточных пробуждений из чтения в ответ на символ элемента управления завершения файла, указанного в структуре CONSOLE_READCONSOLE_CONTROL . Эта функция требует включения расширений команд, стандартного дескриптора выходных данных в виде дескриптора выходных данных консоли и ввода в Юникоде.

Windows Server 2003 и Windows XP/2000: промежуточный компонент чтения не поддерживается.

Режим приготовления — если ENABLE_LINE_INPUT задано с параметром SetConsoleMode в дескрипторе ввода консоли. В режиме приготовления узел консоли предоставит строку редактирования от имени приложения командной строки и вызовы ReadFile или ReadConsole , пока клавишу ВВОД не будет нажиматься.

Промежуточное чтение — это расширение этого поведения в вызове ReadConsole в режиме чтения. Задание флага в dwCtrlWakeupMask в структуре CONSOLE_READCONSOLE_CONTROL и передаче его в pinputControl, так как он вызывает ReadConsole, приведет к тому, что чтение не обязательно ожидает новой строки, но возвращается на указанный символ.

Requirements


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Верхний колонтитул	ConsoleApi.h (через WinCon.h, включая Windows.h)
Библиотека	Kernel32.lib
DLL-библиотеки	Kernel32.dll
Имена Юникода и ANSI	ReadConsoleW (Юникод) и ReadConsoleA (ANSI)