WriteConsoleOutput 함수

아티클
12/13/2023

Important

이 문서에서는 더 이상 에코시스템 로드맵의 일부가 되지 않는 콘솔 플랫폼 기능에 대해 설명합니다. 이 콘텐츠를 신제품에서 사용하지 않는 것이 좋지만, 무기한 앞으로도 기존 사용을 계속 지원할 것입니다. 선호하는 최신 솔루션은 플랫폼 간 시나리오에서 최대 호환성을 위해 가상 터미널 시퀀스에 중점을 둡니다. 이 디자인 결정에 대한 자세한 내용은 클래식 콘솔과 가상 터미널 문서에서 확인할 수 있습니다.

콘솔 화면 버퍼에 있는 문자 셀의 지정된 사각형 블록에 문자 및 색 특성 데이터를 씁니다. 쓸 데이터는 원본 버퍼의 지정된 위치에 있는 해당하는 크기의 사각형 블록에서 가져옵니다.

구문

BOOL WINAPI WriteConsoleOutput(
  _In_          HANDLE      hConsoleOutput,
  _In_    const CHAR_INFO   *lpBuffer,
  _In_          COORD       dwBufferSize,
  _In_          COORD       dwBufferCoord,
  _Inout_       PSMALL_RECT lpWriteRegion
);

매개 변수

hConsoleOutput [in]
콘솔 화면 버퍼에 대한 핸들입니다. 핸들에는 GENERIC_WRITE 액세스 권한이 있어야 합니다. 자세한 내용은 콘솔 버퍼 보안 및 액세스 권한을 참조하세요.

lpBuffer [in]
콘솔 화면 버퍼에 쓸 데이터입니다. 이 포인터는 dwBufferSize 매개 변수에 의해 크기가 지정된 CHAR_INFO 구조체의 2차원 배열의 원점으로 처리됩니다.

dwBufferSize [in]
문자 셀에서 lpBuffer 매개 변수가 가리키는 버퍼의 크기입니다. COORD 구조체의 X 멤버는 열 수입니다. Y 멤버는 행 수입니다.

dwBufferCoord [in]
lpBuffer 매개 변수가 가리키는 버퍼의 왼쪽 위 셀 좌표입니다 . COORD 구조체의 X 멤버는 열이고 Y 멤버는 행입니다.

lpWriteRegion [in, out]
SMALL_RECT 구조체에 대한 포인터입니다. 입력 시 구조체 멤버는 쓸 콘솔 화면 버퍼 사각형의 왼쪽 위와 오른쪽 아래 좌표를 지정합니다. 출력에서 구조체 멤버는 사용된 실제 사각형을 지정합니다.

반환 값

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

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

설명

WriteConsoleOutput 은 원본 버퍼와 대상 화면 버퍼를 2차원 배열(문자 셀의 열 및 행)로 처리합니다. lpWriteRegion 매개 변수가 가리키는 사각형은 콘솔 화면 버퍼에 쓸 블록의 크기와 위치를 지정합니다. 동일한 크기의 사각형은 lpBuffer 배열의 dwBufferCoord 매개 변수 좌표에 있는 왼쪽 위 셀과 함께 있습니다. 이 사각형의 교집합에 있는 셀과 원본 버퍼 사각형(dwBufferSize 매개 변수로 차원이 지정됨)의 데이터는 대상 사각형에 기록됩니다.

해당 원본 위치가 원본 버퍼 사각형의 경계 밖에 있는 대상 사각형의 셀은 쓰기 작업의 영향을 받지 않습니다. 즉, 데이터를 쓸 수 없는 셀입니다.

WriteConsoleOutput이 반환되기 전에 lpWriteRegion의 멤버를 쓰기 작업의 영향을 받는 실제 화면 버퍼 사각형으로 설정합니다. 이 사각형은 원본 버퍼 에 해당 셀이 있는 대상 사각형의 셀을 반영합니다. WriteConsoleOutput 은 대상 사각형의 크기를 콘솔 화면 버퍼의 경계로 잘라내기 때문입니다.

lpWriteRegion에서 지정한 사각형이 콘솔 화면 버퍼의 경계 밖에 완전히 있거나 해당 사각형이 원본 버퍼의 경계 바깥쪽에 완전히 배치된 경우 데이터가 기록되지 않습니다. 이 경우 함수는 오른쪽 멤버가 왼쪽보다 작거나 아래쪽 멤버가위쪽보다 작도록 lpWriteRegion 매개 변수 집합이 가리키는 구조체의 멤버와 함께 반환됩니다. 콘솔 화면 버퍼의 크기를 확인하려면 GetConsoleScreenBufferInfo 함수를 사용합니다.

WriteConsoleOutput 은 커서 위치에 영향을 주지 않습니다.

이 함수는 콘솔의 현재 코드 페이지에서 유니코드 문자 또는 8비트 문자를 사용합니다. 콘솔의 코드 페이지는 처음에 기본적으로 시스템의 OEM 코드 페이지로 설정됩니다. 콘솔의 코드 페이지를 변경하려면 SetConsoleCP 또는 SetConsoleOutputCP 함수를 사용합니다. 레거시 소비자는 chcp 또는 mode con cp select= 명령을 사용할 수도 있지만 새로운 개발에는 추천되지 않습니다.

팁

이 API에는 텍스트 서식 및 커서 위치 지정 시퀀스에 해당하는 가상 터미널이 있습니다. 커서를 삽입할 위치로 이동하고 원하는 서식을 적용한 다음 텍스트를 씁니다. 가상 터미널 시퀀스는 모든 신규 개발 및 진행 중인 개발에 권장됩니다.

예제

예를 들어 문자 및 특성의 읽기 및 쓰기 블록을 참조 하세요.

요구 사항


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