TransactNamedPipe 함수(namedpipeapi.h)

아티클
03/05/2024

메시지를 작성하고 지정된 명명된 파이프에서 메시지를 읽는 함수를 단일 작업으로 결합합니다.

구문

BOOL TransactNamedPipe(
  [in]                HANDLE       hNamedPipe,
  [in]                LPVOID       lpInBuffer,
  [in]                DWORD        nInBufferSize,
  [out]               LPVOID       lpOutBuffer,
  [in]                DWORD        nOutBufferSize,
  [out]               LPDWORD      lpBytesRead,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

매개 변수

[in] hNamedPipe

CreateNamedPipe 또는 CreateFile 함수에서 반환된 명명된 파이프에 대한 핸들입니다.

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

[in] lpInBuffer

파이프에 쓸 데이터를 포함하는 버퍼에 대한 포인터입니다.

[in] nInBufferSize

입력 버퍼의 크기(바이트)입니다.

[out] lpOutBuffer

파이프에서 읽은 데이터를 수신하는 버퍼에 대한 포인터입니다.

[in] nOutBufferSize

출력 버퍼의 크기(바이트)입니다.

[out] lpBytesRead

파이프에서 읽은 바이트 수를 수신하는 변수에 대한 포인터입니다.

lpOverlapped가 NULL이면 lpBytesRead는 NULL일 수 없습니다.

lpOverlapped가 NULL이 아닌 경우 lpBytesRead는 NULL일 수 있습니다. 겹치는 읽기 작업인 경우 GetOverlappedResult를 호출하여 읽은 바이트 수를 가져올 수 있습니다. hNamedPipe가 I/O 완료 포트와 연결된 경우 GetQueuedCompletionStatus를 호출하여 읽은 바이트 수를 가져올 수 있습니다.

[in, out, optional] lpOverlapped

OVERLAPPED 구조에 대한 포인터입니다. hNamedPipe가 FILE_FLAG_OVERLAPPED 열린 경우 이 구조체가 필요합니다.

hNamedPipe가 FILE_FLAG_OVERLAPPED 열린 경우 lpOverlapped 매개 변수는 NULL이 아니어야 합니다. 유효한 OVERLAPPED 구조를 가리킵니다. hNamedPipe가 FILE_FLAG_OVERLAPPED 사용하여 만들어졌고 lpOverlapped가 NULL인 경우 함수가 작업이 완료되었음을 잘못 보고할 수 있습니다.

hNamedPipe가 FILE_FLAG_OVERLAPPED 사용하여 열렸고 lpOverlapped가 NULL이 아닌 경우 TransactNamedPipe는 겹치는 작업으로 실행됩니다. OVERLAPPED 구조에는 CreateEvent 함수를 사용하여 만들 수 있는 수동 재설정 이벤트 개체가 포함되어야 합니다. 작업을 즉시 완료할 수 없는 경우 TransactNamedPipe 는 FALSE 를 반환하고 GetLastError 는 ERROR_IO_PENDING 반환합니다. 이 경우 이벤트 개체는 TransactNamedPipe 가 반환되기 전에 서명되지 않은 상태로 설정되며 트랜잭션이 완료되면 신호 상태로 설정됩니다. 또한 GetQueuedCompletionStatus 또는 GetQueuedCompletionStatusEx 함수를 사용하여 겹치는 작업이 완료되면 알림을 받을 수 있습니다. 이 경우 OVERLAPPED 구조에서 수동 재설정 이벤트를 할당할 필요가 없으며 비동기 읽기 또는 쓰기 작업과 동일한 방식으로 hNamedPipe 에 대해 완료가 발생합니다. 겹치는 작업에 대한 자세한 내용은 파이프를 참조하세요.

hNamedPipe가 FILE_FLAG_OVERLAPPED 사용하여 열리지 않은 경우 TransactNamedPipe는 작업이 완료될 때까지 반환되지 않습니다.

반환 값

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

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

읽을 메시지가 nOutBufferSize 매개 변수에 지정된 버퍼보다 긴 경우 TransactNamedPipe 는 FALSE 를 반환하고 GetLastError 함수는 ERROR_MORE_DATA 반환합니다. 메시지의 나머지 부분을 ReadFile, ReadFileEx 또는 PeekNamedPipe에 대한 후속 호출을 통해 읽을 수 있습니다.

설명

서버가 파이프를 메시지 형식 파이프로 만들지 않았거나 파이프 핸들이 메시지 읽기 모드가 아닌 경우 TransactNamedPipe가 실패합니다. 예를 들어 클라이언트가 서버와 동일한 컴퓨터에서 실행 중이고 \.\pipe\pipename 형식을 사용하여 파이프를 여는 경우 파이프는 명명된 파이프 파일 시스템(NPFS)에 의해 바이트 모드로 열립니다. 클라이언트에서 \\server\pipe\pipename 형식을 사용하는 경우 리디렉션자는 메시지 모드에서 파이프를 엽니다. SetNamedPipeHandleState 함수를 사용하여 바이트 모드 파이프 핸들을 메시지 읽기 모드로 변경할 수 있습니다.

lpOutBuffer 매개 변수로 지정된 버퍼에 데이터를 쓸 때까지 함수를 성공적으로 완료할 수 없습니다. lpOverlapped 매개 변수는 작업이 백그라운드에서 실행되는 동안 호출 스레드가 다른 작업을 수행할 수 있도록 하는 데 사용할 수 있습니다.

명명된 파이프 트랜잭션의 최대 보장 크기는 64KB입니다. 일부 제한된 경우 트랜잭션 및 동적 네트워크 조건에 참여하는 OS 버전에 따라 64KB를 초과하는 트랜잭션이 가능합니다. 그러나 64킬로바이트 이상의 트랜잭션이 성공한다는 보장은 없습니다. 따라서 명명된 파이프 트랜잭션을 64KB의 데이터로 제한하는 것이 좋습니다.

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

예제

예를 들어 명명된 파이프의 트랜잭션을 참조하세요.

요구 사항

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