SetNamedPipeHandleState 함수(namedpipeapi.h)

아티클
03/08/2023

지정된 명명된 파이프의 읽기 모드 및 차단 모드를 설정합니다. 지정된 핸들이 명명된 파이프의 클라이언트 끝에 있고 명명된 파이프 서버 프로세스가 원격 컴퓨터에 있는 경우 함수를 사용하여 로컬 버퍼링을 제어할 수도 있습니다.

구문

BOOL SetNamedPipeHandleState(
  [in]           HANDLE  hNamedPipe,
  [in, optional] LPDWORD lpMode,
  [in, optional] LPDWORD lpMaxCollectionCount,
  [in, optional] LPDWORD lpCollectDataTimeout
);

매개 변수

[in] hNamedPipe

명명된 파이프 instance 대한 핸들입니다. 이 매개 변수는 CreateNamedPipe 함수에서 반환된 파이프의 서버 끝이나 CreateFile 함수에서 반환한 파이프의 클라이언트 끝에 대한 핸들일 수 있습니다. 핸들은 쓰기 전용 또는 읽기/쓰기 파이프에 대해 명명된 파이프에 대한 GENERIC_WRITE 액세스 권한이 있거나 읽기 전용 파이프에 대한 GENERIC_READ 및 FILE_WRITE_ATTRIBUTES 액세스 권한이 있어야 합니다.

이 매개 변수는 CreatePipe 함수에서 반환한 익명 파이프에 대한 핸들일 수도 있습니다.

[in, optional] lpMode

새 파이프 모드입니다. 모드는 읽기 모드 플래그와 대기 모드 플래그의 조합입니다. 모드가 설정되지 않은 경우 이 매개 변수는 NULL 일 수 있습니다. 다음 모드 중 하나를 지정합니다.

모드	의미
PIPE_READMODE_BYTE 0x00000000	데이터는 파이프에서 바이트 스트림으로 읽습니다. 읽기 모드 플래그가 지정되지 않은 경우 이 모드는 기본값입니다.
PIPE_READMODE_MESSAGE 0x00000002	데이터는 파이프에서 메시지 스트림으로 읽습니다. 바이트 형식 파이프에 대해 이 플래그를 지정하면 함수가 실패합니다.

다음 대기 모드 중 하나를 지정할 수 있습니다.

모드	의미
PIPE_WAIT 0x00000000	차단 모드를 사용할 수 있습니다. 대기 모드 플래그가 지정되지 않은 경우 이 모드는 기본값입니다. ReadFile, WriteFile 또는 ConnectNamedPipe 함수에 차단 모드 파이프 핸들을 지정하면 읽을 데이터가 있거나, 모든 데이터가 쓰여지거나, 클라이언트가 연결될 때까지 작업이 완료되지 않습니다. 이 모드를 사용하면 클라이언트 프로세스가 작업을 수행하기 위해 어떤 상황에서는 무기한 대기할 수 있습니다.
PIPE_NOWAIT 0x00000001	차단 해제 모드가 사용하도록 설정됩니다. 이 모드에서는 ReadFile, WriteFile 및 ConnectNamedPipe가 항상 즉시 반환됩니다. 비 차단 모드는 Microsoft LAN Manager 버전 2.0과의 호환성을 위해 지원되며 명명된 파이프를 사용하여 비동기 입력 및 출력(I/O)을 달성하는 데 사용하면 안 됩니다.

모드

의미

PIPE_WAIT
0x00000000

차단 모드를 사용할 수 있습니다. 대기 모드 플래그가 지정되지 않은 경우 이 모드는 기본값입니다. ReadFile, WriteFile 또는 ConnectNamedPipe 함수에 차단 모드 파이프 핸들을 지정하면 읽을 데이터가 있거나, 모든 데이터가 쓰여지거나, 클라이언트가 연결될 때까지 작업이 완료되지 않습니다. 이 모드를 사용하면 클라이언트 프로세스가 작업을 수행하기 위해 어떤 상황에서는 무기한 대기할 수 있습니다.

PIPE_NOWAIT
0x00000001

차단 해제 모드가 사용하도록 설정됩니다. 이 모드에서는 ReadFile, WriteFile 및 ConnectNamedPipe가 항상 즉시 반환됩니다. 비 차단 모드는 Microsoft LAN Manager 버전 2.0과의 호환성을 위해 지원되며 명명된 파이프를 사용하여 비동기 입력 및 출력(I/O)을 달성하는 데 사용하면 안 됩니다.

[in, optional] lpMaxCollectionCount

서버로 전송하기 전에 클라이언트 컴퓨터에서 수집된 최대 바이트 수입니다. 지정된 파이프 핸들이 명명된 파이프의 서버 끝에 있거나 클라이언트 및 서버 프로세스가 동일한 컴퓨터에 있는 경우 이 매개 변수는 NULL 이어야 합니다. 클라이언트 프로세스가 핸들을 만들 때 CreateFile 함수에서 FILE_FLAG_WRITE_THROUGH 플래그를 지정하는 경우 이 매개 변수는 무시됩니다. 컬렉션 수가 설정되지 않은 경우 이 매개 변수는 NULL 일 수 있습니다.

[in, optional] lpCollectDataTimeout

원격 명명된 파이프가 네트워크를 통해 정보를 전송하기 전에 전달할 수 있는 최대 시간(밀리초)입니다. 지정된 파이프 핸들이 명명된 파이프의 서버 끝에 있거나 클라이언트 및 서버 프로세스가 동일한 컴퓨터에 있는 경우 이 매개 변수는 NULL 이어야 합니다. 클라이언트 프로세스가 핸들을 만들 때 CreateFile 함수에서 FILE_FLAG_WRITE_THROUGH 플래그를 지정한 경우 이 매개 변수는 무시됩니다. 컬렉션 수가 설정되지 않은 경우 이 매개 변수는 NULL 일 수 있습니다.

반환 값

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

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

설명

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

예제

예제는 명명된 파이프 클라이언트를 참조하세요.

요구 사항

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