PeekNamedPipe 함수(namedpipeapi.h)

아티클
03/08/2023

명명된 파이프 또는 익명 파이프의 데이터를 파이프에서 제거하지 않고 버퍼에 복사합니다. 또한 파이프의 데이터에 대한 정보를 반환합니다.

구문

BOOL PeekNamedPipe(
  [in]            HANDLE  hNamedPipe,
  [out, optional] LPVOID  lpBuffer,
  [in]            DWORD   nBufferSize,
  [out, optional] LPDWORD lpBytesRead,
  [out, optional] LPDWORD lpTotalBytesAvail,
  [out, optional] LPDWORD lpBytesLeftThisMessage
);

매개 변수

[in] hNamedPipe

파이프에 대한 핸들입니다. 이 매개 변수는 CreateNamedPipe 또는 CreateFile 함수에서 반환한 명명된 파이프 instance 대한 핸들이거나 CreatePipe 함수에서 반환한 익명 파이프의 읽기 끝에 대한 핸들일 수 있습니다. 핸들은 파이프에 대한 GENERIC_READ 액세스 권한이 있어야 합니다.

[out, optional] lpBuffer

파이프에서 읽은 데이터를 수신하는 버퍼에 대한 포인터입니다. 데이터를 읽을 수 없는 경우 이 매개 변수는 NULL 일 수 있습니다.

[in] nBufferSize

lpBuffer 매개 변수에 의해 지정된 버퍼의 크기(바이트)입니다. lpBuffer가 NULL인 경우 이 매개 변수는 무시됩니다.

[out, optional] lpBytesRead

파이프에서 읽은 바이트 수를 수신하는 변수에 대한 포인터입니다. 데이터를 읽을 수 없는 경우 이 매개 변수는 NULL 일 수 있습니다.

[out, optional] lpTotalBytesAvail

파이프에서 읽을 수 있는 총 바이트 수를 수신하는 변수에 대한 포인터입니다. 데이터를 읽을 수 없는 경우 이 매개 변수는 NULL 일 수 있습니다.

[out, optional] lpBytesLeftThisMessage

이 메시지에 남아 있는 바이트 수를 수신하는 변수에 대한 포인터입니다. 이 매개 변수는 바이트 형식 명명된 파이프 또는 익명 파이프의 경우 0이 됩니다. 데이터를 읽을 수 없는 경우 이 매개 변수는 NULL 일 수 있습니다.

반환 값

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

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

설명

PeekNamedPipe 함수는 다음 예외를 제외하고 ReadFile 함수와 유사합니다.

데이터는 CreateNamedPipe로 지정된 모드에서 읽습니다. 예를 들어 PIPE_TYPE_MESSAGE 사용하여 파이프 만들기 | PIPE_READMODE_MESSAGE. SetNamedPipeHandleState를 사용하여 모드를 PIPE_READMODE_BYTE 경우 ReadFile은 바이트 모드로 읽지만 PeekNamedPipe는 메시지 모드에서 계속 읽습니다.
파이프에서 읽은 데이터는 파이프의 버퍼에서 제거되지 않습니다.
함수는 파이프의 내용에 대한 추가 정보를 반환할 수 있습니다.
함수는 파이프에 데이터가 없더라도 항상 단일 스레드 애플리케이션에서 즉시 반환됩니다. 명명된 파이프 핸들(차단 또는 비블로킹)의 대기 모드는 함수에 영향을 주지 않습니다.

참고PeekNamedPipe 함수는 다중 스레드 애플리케이션의 동기 핸들에서 호출될 때 모든 I/O 함수가 할 수 있는 것과 동일한 방식으로 스레드 실행을 차단할 수 있습니다. 이 조건을 방지하려면 비동기 I/O에 대해 만든 파이프 핸들을 사용합니다.

지정된 핸들이 바이트 읽기 모드의 명명된 파이프 핸들인 경우 함수는 nBufferSize에 지정된 크기까지 사용 가능한 모든 바이트를 읽습니다. 메시지 읽기 모드의 명명된 파이프 핸들의 경우 함수는 파이프에서 다음 메시지를 읽습니다. 메시지가 nBufferSize보다 크면 지정된 바이트 수를 읽은 후 함수가 TRUE 를 반환합니다. 이 경우 lpBytesLeftThisMessage 는 메시지에 남아 있는 바이트 수를 받습니다.

Windows 10 버전 1709: 파이프는 앱 컨테이너 내에서만 지원됩니다. 즉, 한 UWP 프로세스에서 동일한 앱의 일부인 다른 UWP 프로세스까지 지원됩니다. 또한 명명된 파이프는 파이프 이름에 대한 구문을 \\.\pipe\LOCAL\ 사용해야 합니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 2000 Professional [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows 2000 Server [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	namedpipeapi.h
라이브러리	Kernel32.lib
DLL	Kernel32.dll