ReadConsole 함수

아티클
10/23/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, optional]
읽기 작업의 끝을 알리는 컨트롤 문자를 지정하는 CONSOLE_READCONSOLE_CONTROL 구조체에 대한 포인터입니다. 이 매개 변수는 NULL일 수 있습니다.

이 매개 변수에는 기본적으로 유니코드 입력이 필요합니다. ANSI 모드의 경우 이 매개 변수를 NULL로 설정합니다.

반환 값

함수가 성공하면 반환 값이 0이 아닙니다.

함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

설명

ReadConsole 은 콘솔의 입력 버퍼에서 키보드 입력을 읽습니다. 유니코드(와이드 문자) 또는 ANSI 모드에서 읽을 수 있다는 점을 제외하고 ReadFile 함수처럼 동작합니다. 두 모드와 호환되는 단일 원본 집합을 기본 애플리케이션을 사용하려면 ReadFile 대신 ReadConsole을 사용합니다. 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로 설정된 경우입니다. 조리된 모드에서 콘솔 호스트는 명령줄 애플리케이션을 대신하여 편집줄을 제공하고 Enter 키를 누를 때까지 ReadFile 또는 ReadConsole에 대한 호출이 반환되지 않습니다.

중간 읽기는 조리된 읽기 모드의 ReadConsole 호출에서 해당 동작을 확대한 것입니다. CONSOLE_READCONSOLE_CONTROL 구조체의 dwCtrlWakeupMask에서 플래그를 설정하고 ReadConsole을 호출할 때 pinputControl에 전달하면 읽기가 반드시 줄 바꿈을 기다리는 것은 아니지만 지정된 문자에서도 반환됩니다.

요구 사항


지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
헤더	ConsoleApi.h(WinCon.h를 통해, Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll
유니코드 및 ANSI 이름	ReadConsoleW (유니코드) 및 ReadConsoleA (ANSI)